The CIServer Control Reference
The Crescent Internet ToolPak TCP/IP Server Control Reference
Related Topics

Control Files

CISERVER.OCX

Object Types

CISERVER
Clients collection
Client object

Purpose

The Crescent Internet ToolPak TCP/IP Server (CIServer) control enables you to build custom TCP/IP server applications. Unlike the more general purpose TCP (CITCP) control, CIServer controls server applications and does not contain client functionality.

The Clients collection contains Client objects that represent zero or more clients that are connected to the Server control.

The Clients collection has the Count property and the Item method, which behave like they do in other standard Visual Basic collections. However, the Add and Remove methods are not implemented for the Clients collection.

The Client object represents a TCP/IP connection to the Server Socket. Client objects are only part of the Clients collection while the connection is active. If valid references to the Client object remain when the connection becomes inactive, however, the Client object remains. In this case, the remaining Client object is not part of the collection.

Comments

You access all client connections through a collection property in CIServer. Therefore, you do not need to create a control array to support multiple clients simultaneously.

CIServer Properties

About	Clients c	ListenMode c
Index Object	Left Parent	Name Port c
ServerAddress c	Tag	Top
CIServer Events

ClientSocketError c	ConnectionAttempt c	ConnectionClosed c
PacketReceived c	SocketError c
CIServer Methods

None.

Clients Collection Properties

Count

Clients Collection Events

None.

Clients Collection Methods

Item
Client Object Properties

Address c	Key c	RawPacket c
Socket c	Status c
Client Object Events

None.

Client Object Methods

CloseConnection c	Send c	SendB c
c  A custom or modified property, method, or event.


Clients Property

Applies To

CIServer

Purpose

The Clients property contains the current collection of Client objects.

Syntax

[Form.]CIServer1.Clients

Data Type

Clients collection

Usage

Read-only at run time. Unavailable at design time.

Comments

The Clients collection represents the clients currently connected to a server control. The Clients collection behaves like other standard Visual Basic collections. See the Client object for a list of its properties.


ListenMode Property

Applies To

CIServer

Purpose

The ListenMode property sets or returns the current listening mode of the CIServer control.

Syntax

[Form.]CIServer.ListenMode [ = Value]

Data Type

Integer

Usage

Read/Write at design time and run time.

Comments

The ListenMode property determines if the control is actively listening for client connection requests. If ListenMode is set to SERVER_MODE_ACTIVE, incoming connection attempts fire the ConnectionAttempt event. If ListenMode is set to SERVER_MODE_INACTIVE, connection attempts are ignored.

See Also

ConnectionAttempt event, ListenMode constants


Port Property

Applies To

CIServer

Purpose

The Port property sets the TCP/IP port number the CIServer control will use.

Syntax

[Form.]CIServer.Port [ = Value]

Data Type

Integer

Usage

Read/Write at design time and run time.

Comments

The Port property combines with your machine’s IP address to create an address that client machines use to connect to you. Although you are free to use any port you would like, it is general practice to use ports under 1024 for system purposes. Also, be aware that other Internet protocols (FTP, HTTP, and so on) use default port numbers for their protocols.


ServerAddress Property

Applies To

CIServer

Purpose

The ServerAddress property sets the TCP/IP address the CIServer control uses.

Syntax

[Form.]CIServer.ServerAddress [ = Value]

Data Type

String

Usage

Read/Write at design time and run time.

Comments

Use the ServerAddress property to specify a TCP/IP address other than each machine’s default. This enables you to implement a virtual host. In order to use this feature, you must set up each machine with more than one TCP/IP address. You can do this through the Control Panel. If ServerAddress is an empty string, your default TCP/IP address is used. You cannot change this property during run time if you are actively listening for connections.


ClientSocketError Event

Applies To

CIServer

Purpose

The ClientSocketError event fires when a client has a Windows Sockets error.

Syntax

Sub CIServer_ClientSocketError(ByVal FromClient As Object, ByValErrorNumber As Integer)

Comments

Use the ClientSocketError event to monitor the WinSock activity. The FromClient parameter holds a reference to the Client object that generated the error. The ErrorNumber parameter identifies the WinSock error that occurred. The CITPAK.BAS file lists these errors.

You can pass the number that is returned by this ClientSocketError event to the WSAErrDescription function (in CITPAK.BAS) to get a description of the WinSock error. To get an abbreviated description of the WinSock error, you can optionally pass the ConstName parameter.

The following declaration is for the WSAErrDescription function:

Public Function WSAErrDescription(Err As Integer, Optional ByRefConstName As Variant) As String


ConnectionAttempt Event

Applies To

CIServer

Purpose

The ConnectionAttempt event fires when a client tries to connect to the CIServer control.

Syntax

Sub CIServer_ConnectionAttempt(ByVal NewClient As Object,_AcceptConnection As Boolean)

Comments

You use the ConnectionAttempt event to monitor client connection attempts. The NewClient parameter is a Client object that contains information about the client connecting to you. You can deny the connection by setting the AcceptConnection parameter to false. If you accept the connection, the Client object gets added to the Clients collection after returning from this event.

Examples

This example shows a server application that accepts a maximum of 5 connections at one time;

Sub CIServer_ConnectionAttempt(ByVal NewClient As Object, AcceptConnection As Boolean)

‘—Too many connections. Do not accept

If CIServer.Clients.Count = 5 Then
NewClient.Send Connection refused - Too many clients.
AcceptConnection = False
Exit Function
End If

‘--- We want the connection so send Welcome String

NewClient.Send Welcome to my server application!
End Sub


ConnectionClosed Event

Applies To

CIServer

Purpose

The ConnectionClosed event fires when a client application terminates a connection.

Syntax

Sub CIServer_ConnectionClosed(ByVal FromClient As Object)

Comments

Use the ConnectClosed event to monitor when a client application terminates a connection. This event does not fire if you terminate the connection manually. The FromClient parameter holds a reference to the ClientObject that this event refers to. If you are holding any external references to this Client, you should set them to nothing so the object can be deleted. The object is also removed from the Clients collection.


PacketReceived Event

Applies To

CIServer

Purpose

The PacketReceived event fires when the CIServer control receives a packet from any of the connected clients.

Syntax

Sub CIServer1_PacketReceived(ByVal FromClient As Object, PacketAsVariant, ByVal BytesRec As Integer)

Comments

The FromClient parameter holds a reference to a Client object that sent the packet. The Packet parameter is the actual data received from the server. Its contents varies, depending on the method used to obtain the packet. The BytesRec  value is the number of bytes in the current packet (which may be different than the total number of bytes received by any given operation).


SocketError Event

Applies To

CIServer

Purpose

The SocketError event fires when the CIServer socket has a Windows Sockets error.

Syntax

Sub CIServer_SocketError(ByValErrorNumber As Integer)

Comments

Use the SocketError event to monitor the WinSock activity. The ErrorNumber parameter identifies the WinSock error that occurred. The CITPAK.BAS file lists these errors.

You can pass the number that is returned by this ClientSocketError event to the WSAErrDescription function (in CITPAK.BAS) to get a description of the WinSock error. To get an abbreviated description of the WinSock error, you can optionally pass the ConstName parameter.

The following declaration is for the WSAErrDescription function:

Public Function WSAErrDescription(Err As Integer, Optional ByRefConstName As Variant) As String


Address Property

Applies To

Client Object

Purpose

The Address property returns the TCP/IP address of the connected client.

Syntax

[String$ =]Client.Address

Data Type

String

Usage

Read only at  run time.

Comments

The Address property allows you to see who is connecting to you. You can use this to log accesses, or to decide if you want to accept the connection.


Key Property

Applies To

Client Object

Purpose

The Key property sets or returns a string that is associated with the client.

Syntax

Client.Key [= Value]

Data Type

String

Usage

Read/write at  run time.

Comments

Use the Key property to assign a value to a client connection.  You can use the value later to retrieve that client from the Clients collection.


RawPacket Property

Applies To

Client Object

Purpose

The RawPacket property returns an array of bytes that represent the incoming packet without any ANSI-to-UNICODE conversion.

Syntax

[Value =] Client.RawPacket

Data Type

Variant

Usage

Read only at  run time.

Comments

The RawPacket property gives you access to the incoming packet as an array of bytes. There is no need to use this property in English Language versions of Windows, but it is available should you want your data in that format. In international versions of Windows that use multibyte character sets, this property allows you to receive binary data without corruption. The RawPacket property does not corrupt the data because an  ANSI-to-UNICODE translation occurs in the PacketReceived event. This property only contains data during a PacketReceived event.


Socket Property

Applies To

Client Object

Purpose

The Socket property returns the socket handle of the client. The socket handle is a
WinSock-generated socket number.

Syntax

[Value =]Client.Socket

Data Type

Long

Usage

Read only at  run time.

Comments

The Socket property allows you to get the Windows Socket handle of the client connection.


Status Property

Applies To

Client Object

Purpose

The Status property returns the current connection status of the client. The value is either 0 (not connected) or -1 (connected).

Syntax

[Value =]Client.Status

Data Type

Integer

Usage

Read only at  run time.


CloseConnection Method

Applies To

Client Object

Purpose

The server uses this method to close a client connection.

Syntax

Client.CloseConnection

Return Type

None

Comments

You can use either of the following two ways to obtain the client object for this method:

Use the first parameter inside each event of CIServer. This parameter is a client object with which you can call methods directly.

Use any client object in CIServer.Clients. This is a good way to perform a method globally.  For example:

For Each object in CIServer.Clients
‘ Call any client method here
object.method
Next


Send Method

Applies To

Client Object

Purpose

The server uses this method to send data to the client that is associated with the object.

Syntax

Client.Send string

Data Type

String

Return Type

None

Comments

The Send method differs from the SendB method by sending a string instead of a binary representation of the data. For example, the following Send example sends the string “1” to the client:

Dim i As Integer
i = 1
Client.Send i   ‘ Send the string representation of i

The following SendB example sends the binary equivalent of the integer i, which is two bytes (Chr$(0) and Chr$(1)):

Dim i As Integer
i = 1
Client.SendB i  ‘ Send the binary equivalent of the integer i

You can use either of the following two ways to obtain the client object for this method:

Use the first parameter inside each event of CIServer. This parameter is a client object with which you can call methods directly.

Use any client object in CIServer.Clients. This is a good way to perform a method globally.  For example:

For Each object in CIServer.Clients
‘ Call any client method here
object.method
Next

See Also

SendB Method


SendB Method

Applies To

Client Object

Purpose

Sends to the client a binary representation of the supplied parameter. The number of bytes sent depends upon the size of the data type. For example, the Integer data type is 2 bytes, the Long data type is 4 bytes, and so on.

Syntax

Client.SendB string

Data Type

Binary

Comments

The SendB method differs from the Send method by sending a binary instead of a string representation of the data. For example, the following Send example sends the string “1” to the client:

Dim i As Integer
i = 1
Client.Send i   ‘ Send the string representation of i

The following SendB example sends the binary equivalent of the integer i, which is two bytes (Chr$(0) and Chr$(1)):

Dim i As Integer
i = 1
Client.SendB i  ‘ Send the binary equivalent of the integer i

You can use either of the following two ways to obtain the client object for this method:

Use the first parameter inside each event of CIServer. This parameter is a client object with which you can call methods directly.

Use any client object in CIServer.Clients. This is a good way to perform a method globally.  For example:

For Each object in CIServer.Clients
‘ Call any client method here
object.method
Next

See Also

Send Method


Related Topics

What Is the CIServer Control?
Acting as a TCP Server
Accepting Connections to the Server

Back to the CIServer Reference


What Is the CIServer Control?
Related Topics

The Crescent Internet ToolPak TCP/IP Server (CIServer) control enables Visual Basic programmers to build customized server applications.

The CIServer control has a simple programming interface with which you set property values and call methods to perform the desired tasks. The methods take the necessary data directly from the property sheet and act as a server by listening on a port for connection requests.


Programming Tasks

The following sections describe how to program some simple tasks with the CIServer control:

Acting as a TCP/IP server.

Accepting connections to the server.


Acting as a TCP Server
Related Topics

Set these properties:

Port

ListenMode

The code looks like this:

Form_Load
CIServer1.Port = 2000
CIServer1.ListenMode = SERVER_MODE_ACTIVE


Accepting Connections to the Server
Related Topics

For performance or security reasons, you might want to limit or require validation of logons. CIServer enables you to create an application that limits the number of logons to the server.  The ConnectionAttempt event executes whenever a client tries to connect to your server. When the connection attempt fires ConnectionAttempt, you can add code that validates and/or inititializes a connection.

Perform these steps:

1.	Define the MAX_CLIENTS constant as the maximum number of client connections to the server.

2.	Wait for the ConnectionAttempt event to fire.

3.	Compare CIServer.Clients.Count with MAX_CLIENTS.

Here is a simple code example:

Private Sub CIServer1_ConnectionAttempt(ByVal NewClient As Object,
AcceptConnection As Boolean)

' MAX_CLIENTS is a constant defined elsewhere

If CIServer1.Clients.Count >= MAX_CLIENTS Then
NewClient.Send Server full, try again later & vbCrLf
AcceptConnection = False
Else
NewClient.Send Welcome & vbCrLf
AcceptConnection = True
End If
End Sub